<?php

declare(strict_types=1);

namespace WebTus;

/**
 * 文件存储定义
 * Interface TusStoreInterface
 */
interface TusStoreInterface
{
    /**
     * @param string $id
     * @return bool
     */
    public function lock(string $id): bool;

    /**
     * @param string $id
     * @return void
     */
    public function unlock(string $id);

    /**
     * 获取文件Hash信息
     * @param string $hash
     * @return TusFileHash|null
     */
    public function getFileHash(string $hash): ?TusFileHash;

    /**
     * 获取文件信息
     * @param string $id
     * @return TusFileInfo|null
     */
    public function getInfo(string $id): ?TusFileInfo;

    /**
     * 通过文件路径获取info
     * @param string $file
     * @return TusFileInfo|null
     */
    public function getFile2Info(string $file): ?TusFileInfo;

    /**
     * 通过hash获取info
     * @param string $hash
     * @return TusFileInfo|null
     */
    public function getHash2Info(string $hash): ?TusFileInfo;

    /**
     * 新建文件信息 成功返回写入大小 存在返回true 失败false
     * @param TusFileInfo $info
     * @return bool
     */
    public function newInfo(TusFileInfo &$info): bool;

    /**
     * 更新临时文件信息
     * @param TusFileInfo $info
     * @return int|false
     */
    public function updateTmpInfo(TusFileInfo $info);

    /**
     * 写入文件
     * @param resource|string $in
     * @param TusFileInfo $info
     * @param int $maxSize 读取数据的最大值 0不限制
     * @return int
     */
    public function write($in, TusFileInfo $info, int $maxSize = 0): int;

    /**
     * 分块上传文件合并处理
     * @param TusFileInfo $info
     * @return bool
     */
    public function merge(TusFileInfo $info): bool;

    /**
     * 输出文件到$out
     * @param TusFileInfo|null $info
     * @param int $offset 读取偏移 0不限制
     * @param int $size 读取大小 -1不限制
     * @return string|TusReadFile
     */
    public function output(TusFileInfo $info = null, int $offset = 0, int $size = -1);

    /**
     * @param TusFileInfo $info
     * @return void
     */
    public function delete(TusFileInfo $info);

    /**
     * 上传完成后的处理
     * @param TusFileInfo $info
     * @return void
     * @throws \Exception
     */
    public function complete(TusFileInfo $info);
}
